home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 076-100 / disk_077 / introduction < prev    next >
Text File  |  1992-05-06  |  16KB  |  349 lines

  1.             Brief Introduction to Draco
  2.  
  3. There are two disks in the Draco set. The first one, "Draco SYS" is the one
  4. to boot from. It contains all of the executables, libraries, include files,
  5. and much of the normal WorkBench disk stuff. There is some room on it for
  6. stuff you might want on the disk you boot. In particular you may want to
  7. replace Ded (Draco editor) and Ed (regular AmigaDOS editor) with
  8. MicroEmacs. The second disk, "Draco Other" contains various pieces of
  9. documentation and sample Draco programs. Note that the way things are set
  10. up, the boot disk contains everything you need for compiling and running
  11. Draco programs - your entire second drive is available for your stuff.
  12.  
  13.  
  14. Short, Quick Example
  15.  
  16. To get you started real quick, here is what you need to do to enter,
  17. compile, link, and run a simple Draco program. (Throughout, I assume you
  18. have booted from the "Draco SYS" disk.)
  19.  
  20.     1> cd df1:
  21.     1> ded test.d
  22.  
  23.     (you are now in the Draco editor - just enter the program as it's
  24.     written here, then continue with the control sequence)
  25.  
  26.     proc main()void:
  27.  
  28.     writeln("Hello there world!");
  29.     corp;
  30.  
  31.     (now write out the file and exit Ded with)
  32.  
  33.     <ESCAPE-e>
  34.  
  35.     (you should now be back in your AmigaDOS window)
  36.  
  37.     1> draco test
  38.  
  39.     (if you got any error messages, go back into the editor by again
  40.     entering 'ded test.d' and repeating from there. You would normally
  41.     be running the editor in the background and just writing out the
  42.     file and switching windows, but I won't get into that here.)
  43.  
  44.     1> ex dr1 test
  45.  
  46.     ('ex' is just 'Execute' renamed, and 'dr1' is a script in 's:'
  47.     which will link a single Draco object file with the appropriate
  48.     libraries and startup sequence)
  49.     
  50.     1> test
  51.  
  52.     (your program now runs)
  53.  
  54.  
  55. Batch Files
  56.  
  57. Directory s: contains a number of execute files which I've set up to help
  58. out in linking Draco programs. Their names are of the form <'dr' N>, <'dr'
  59. N 'lib'> and <'dr' N 'lib2'>, where 'N' is between 1 and 4. 'N' specifies
  60. the number of object files (.r files produced by running the compiler) to
  61. be linked. The first set link programs not requiring any libraries other
  62. than the Draco run-time and I/O libraries and the Amiga dos and exec
  63. libraries. The second set allows one library, and the third allows two. If
  64. you need more than that, you should probably set up a "with" file for the
  65. linker. As an example, to compile and link a program which has two source
  66. files, "myprog1.d" and "myprog2.d", which uses the Draco I/O and memory
  67. management routines (located in drlib:drio.lib), you would use
  68.  
  69.     1> draco myprog1 myprog2
  70.     1> ex dr2 myprog1 myprog2
  71.  
  72. The final program is left in a file named by the first '.r' file
  73. specified. 'ex' is just the 'Execute' command renamed.
  74.  
  75. If you wanted to link a program which uses the Amiga graphics and intuition
  76. libraries, and had only one source file, test.d, you would use
  77.  
  78.     1> draco test
  79.     1> ex dr1lib2 graphics intuition test
  80.  
  81. The final batch file is 'drraw', which will link a single source file which
  82. does NOT use any of the Draco I/O or storage allocation facilities, and
  83. does not use any Amiga library other than 'dos.library'. This is used to
  84. link some sample programs which were written before the Draco I/O system
  85. was ported to the Amiga.
  86.  
  87.  
  88. BLink
  89.  
  90. The linker present and used by the Draco stuff is BLink, which is a
  91. shareware product produced by The Software Distillery. You can use the
  92. standard linker ALink instead, so long as you remove the 'smallcode'
  93. directive from all of the batch files. I plan on porting my own linker
  94. eventually, and it should allow the intermediate .r files to be
  95. considerably smaller, and will also produce smaller final program files for
  96. many programs. If you find BLink of use, you should consider a donation to
  97. The Software Distillery.
  98.  
  99.  
  100. What's on 'Draco Other'
  101.  
  102. The 'Draco Other' disk contains four directories containing sample source
  103. files. 'misc' contains three separate programs, 'intuition', 'view', and
  104. 'cmp'. 'intuition' is a program which demonstrates the use of Intuition
  105. Screens, Windows, Menus, etc. and a few of the RastPort oriented Graphics
  106. calls, including a bit of animation. It has some explanatory comments in
  107. it. 'view' is a program which demonstrates taking over the entire graphics
  108. subsystem, temporarily suspending the Intuition user interface. I wrote it
  109. to explore how to have a 24 line hi-resolution text screen sometimes mostly
  110. covered by a low-resolution graphics screen. I need the combination for a
  111. game I plan to port to the Amiga. 'cmp' is the source to the 'Cmp' program
  112. on the "Draco SYS" disk. It is a fairly portable program (also runs on CP/
  113. M-80) using the Draco I/O system and my CRT library. It provides full-
  114. screen comparison of files in both binary and text modes. I find it quite
  115. useful when working on the compiler - I make changes to the compiler, check
  116. them out with test sources, then compile the compiler. If the resulting
  117. version runs, I get IT to compile the compiler and compare the .r files -
  118. they should be the same. If they aren't, 'Cmp' is very handy for finding
  119. the differences.
  120.  
  121. To compile, link and run 'intuition', type
  122.  
  123.     1> draco intuition
  124.     1> blink with intuition.w
  125.     1> intuition
  126.  
  127. To compile, link and run 'view', type
  128.  
  129.     1> draco view
  130.     1> blink with view.w
  131.     1> view
  132.  
  133. I don't currently know why the text ViewPort jumps around when the graphics
  134. one is sliding up and down, but my current suspicion is that the Copper
  135. lists in the View and ViewPort are being freed and rebuilt by MakeVPort
  136. while the hardware is still accessing them. LATER NOTE: this is indeed the
  137. case - in another version, I've double buffered the copper lists and the
  138. bouncing goes away.
  139.  
  140. To compile, link and run 'cmp', type
  141.  
  142.     1> draco cmp
  143.     1> ex dr1lib crt cmp
  144.     1> cmp -?
  145.  
  146. The second directory, 'quest', contains the complete source for the driver
  147. portion of a CRT/text oriented adventure game. It is written in a fairly
  148. portable way using Draco I/O constructs and the CRT library. The same
  149. source (except for the CRT_Initialize call) runs on CP/M-80. What is needed
  150. here is a useful scenario. To compile, link, and run 'quest', type
  151.  
  152.     1> draco qmain qparse qcrt qlist
  153.     1> blink with q.w
  154.     1> quest
  155.  
  156. Note that it currently only uses a 24 line window. You can change 'qcrt' to
  157. call CRT_Initialize with different parameters if you want. When highlighted
  158. 'M O R E' appears down the right side of the text subwindow, pressing any
  159. key will allow it to continue. All output is automatically word wrapped and
  160. paginated by the quest output routines. Some commands that the little test
  161. scenario understands are:
  162.  
  163.     n, north, s, south, e, east, w, west, pick up, put down, look, long, dump
  164.  
  165. 'dump' will dump out the parser's internal structures, including the
  166. grammar it is accepting. Such a command would not normally be present.
  167.  
  168. The third directory, 'rawSamples', contains programs that I wrote before I
  169. had ported the I/O library. Thus, they don't use Draco's I/O constructs but
  170. instead directly call the AmigaDOS I/O routines. The four programs are
  171. 'entab', 'detab', 'uuencode' and 'uudecode'. 'entab' and 'detab' both strip
  172. carriage-returns from files, stop when they hit the CP/M EOF character
  173. (CNTL-Z, which is used by the XMODEM protocol) and either change blanks to
  174. standard 8-column tabstops when possible, or expand such tabstops into
  175. blanks. (If you are going to use the standard Amiga editor, Ed, you will
  176. want to expand tabs, since Ed doesn't handle them properly.) 'uuencode' and
  177. 'uudecode' are standard utilities for encoding and decoding binary files as
  178. character data which can be transmitted as mail over computer networks,
  179. etc. Note that they use the newer form of the 'uuencode' protocol, which
  180. uses graves (`) instead of blanks. All four programs are linked using
  181. 'drraw'. E.g.
  182.  
  183.     1> draco entab
  184.     1> ex drraw entab
  185.  
  186. The fourth directory, 'samples', contains simple programs illustrating
  187. various aspects of the language. The 'Read.Me' file in that directory
  188. explains a bit about each one.
  189.  
  190.  
  191. Exec Libraries
  192.  
  193. The Amiga documentation shows that the Exec routine "OpenLibrary" is to be
  194. used to open either a resident or disk based library. This returns a
  195. pointer to the library node, which is to be in A6 whenever an entry from
  196. that library is called. In C, the library node pointer is supposed to be
  197. assigned to a specifically named variable which the assembler interface
  198. stubs access as a global to get the value to pass in A6. Draco doesn't have
  199. such named global variables, so a different technique is used. The 'convfd'
  200. program, which takes the ".fd" files and produces the interface libraries,
  201. also produces private versions of "OpenLibrary" and "CloseLibrary" for each
  202. library. They are called "OpenXXXLibrary" and "CloseXXXLibrary", where XXX
  203. is the name of the library. "OpenXXXLibrary" is passed the desired version
  204. number as a 'ulong' and returns the library node pointer. For example, to
  205. open the Intuition library, the following would be declared:
  206.  
  207.     extern
  208.     OpenIntuitionLibrary(ulong version)*IntuitionBase_t,
  209.     CloseIntuitionLibrary()void;
  210.  
  211. For resident libraries (those for which there isn't a ".library" file in
  212. the "libs:" directory), the close call isn't really needed, but should be
  213. used for compatibility with future Amiga systems.
  214.  
  215. A couple of the devices in the Amiga system are similar to libraries in
  216. that they have some independent routines, accessed in a library-like
  217. manner, associated with them. ".fd" files exist for them, and 'convfd'
  218. produces interface routines. With these calls, the device node is used in a
  219. similar way, but the standard "OpenDevice" call only returns it indirectly,
  220. in the IO request block. To use these in Draco, use "OpenDevice" and
  221. "CloseDevice" as the RKM indicates. If you want to call the related,
  222. library-like functions, you must first call "SetXXXDevice", where XXX is
  223. the device name. You pass it the Device pointer extracted from the IO
  224. request block. Sample declarations (for timer.device):
  225.  
  226.     extern
  227.     SetTimerDevice(*Device_t timerDevice)void,
  228.     SubTime(*TimeVal_t dest, source)void;
  229.  
  230. Some of the resources (e.g. disk.resource, cia.resource) operate in an
  231. analagous manner.
  232.  
  233.  
  234. Draco Libraries
  235.  
  236. Proper opening/closing is also required for the Draco specific libraries.
  237. The startup file that is linked in by the batch files described previously
  238. will automatically initialize the commonly used Draco libraries. Thus, you
  239. can use Draco's I/O, storage allocation and parameter accessing libraries
  240. without any special setup. The problem with this scheme is that it forces
  241. all programs to contain most of the referenced libraries, because BLink
  242. (and ALink) insists on loading all routines from any unit from which any
  243. routine is needed. If I ever get around to porting my linker, programs
  244. produced with Draco using these libraries will become considerably smaller.
  245. You can set up your own batch files (or 'with' linker files) which
  246. reference the alternate startup file (drlib:drstart0.o instead of drlib:
  247. drstart.o). If you do this, you must be aware of the following needs:
  248.  
  249. Any use of a Draco I/O construct or associated I/O call requires that the
  250. I/O library be initialized. This is done by calling
  251.  
  252.     _IO_initialize();
  253.  
  254. This routine will open the DOS library also. Any use of the new/free
  255. constructs or the Malloc/Mfree calls requires that the storage allocation
  256. sub-library be initialized via
  257.  
  258.     _M_initialize();
  259.  
  260. This routine will open the Exec library (since that's where AllocMem is).
  261. Any use of the parameter accessing routines requires a previous call to
  262.  
  263.     _Pars_initialize();
  264.  
  265. Regardless of which startup file you are using, any use of the CRT terminal
  266. library requires that it be initialized (and a CON: window created for it
  267. to use). The CON: window needs to be closed when you are done, also. These
  268. jobs are handled by
  269.  
  270.     extern
  271.     CRT_Initialize(*char windowName; ushort lineCount, columnCount)void,
  272.     CRT_Terminate()void;
  273.  
  274. which are declared (along with all of the other CRT routines) in 'include:
  275. crt.g'. The 'windowName' is used as the window title, and the line and
  276. column counts are the text line and column counts desired. On an interlaced
  277. screen, sizes from 16 lines to 50 lines and 32 columns to 80 columns are
  278. supported. The forms input routines in the CRT library are a separate
  279. sublibrary which must be initialized separately if needed. This is done by
  280.  
  281.    _F_initialize();
  282.  
  283. If the forms routines are used, the storage allocator must also be set up,
  284. as previously described.
  285.  
  286. To summarize, most Draco programs will use one of the normal batch files
  287. (or a with file similarly set up) to link programs. These programs will
  288. use drstart.o to start up, which will automatically call _IO_initialize,
  289. _M_initialize and _Pars_initialize. If you want to cut down on program
  290. size, don't use the I/O or storage allocation facilities in Draco, link
  291. using drstart0.o, and talk directly to AmigaDOS yourself. (Interface
  292. routines for AmigaDOS are in dos.lib and declarations are in include:
  293. libraries/dos.g and dosextens.g.)
  294.  
  295.  
  296. Making Your Own Boot Disks
  297.  
  298. The only things that you really need on a boot disk are an assign of
  299. 'include:' to where the include directories are; an assign of 'drlib:'
  300. to where the '.lib' files are (and dracoErrors and the startup '.o'
  301. files); and a stack size of at least 16000.
  302.  
  303.  
  304. Current State of this Distribution
  305.  
  306.     compiler - types 'float' and 'lfloat' are predefined, but if you try to
  307.     do much with them, you will probably crash the compiler. Operator
  308.     types are totally untested in this compiler and will also probably
  309.     crash it. There is still at least one bug associated with undefined
  310.     symbols - if the compiler aborts with 'program buffer overflow'
  311.     after messages about undefined symbols or something similar, just
  312.     try compiling again after fixing the previous errors. Code quality
  313.     is not so good. It's about on par with Lattice or Aztec if you
  314.     cripple them by not using register variables and force long
  315.     addressing modes (which is what the Draco compiler currently does).
  316.     Also, everything is stacked and unstacked on each procedure entry/
  317.     exit. A peepholer is needed, especially for some MOVE/MOVE stuff.
  318.  
  319.     Ded editor - needs proper support for multiple windows into a single
  320.     file. The documentation needs properly updating to describe the
  321.     multiple windows. File reading/writing is slow (it goes through the
  322.     standard Draco I/O stuff - I should either rewrite it to use the
  323.     native AmigaDOS calls or put code into LineRead and LineWrite so
  324.     that they can directly access the file's buffer). Long file names
  325.     are not handled at all (they will mess up the display). There are
  326.     problems with special characters (including tabs) in input lines -
  327.     the editor gets confused by quotes and doesn't expand them because
  328.     it thinks they are inside a string. I'm not sure what to do about
  329.     this one. No menu or mouse support at all. About the only one that
  330.     I personally would find useful is using the mouse to move the text
  331.     cursor. Still some problems with the definition of "words". Again,
  332.     I'm not sure how to fix this - the rules are already pretty tricky.
  333.     Still some minor problem with INDENT and OUTDENT.
  334.  
  335.     Quest - needs a scenario. Needs graphicizing.
  336.  
  337. LAST MINUTE ADDITION:
  338.  
  339.     While waiting for Commodore to OK this distribution's including my
  340. translated versions of their copyrighted include files, I and a friend got
  341. ambitious and started implementing Old Empire in Draco for the Amiga.
  342. We're most of the way there, but its not done yet. We've actually been
  343. playing for about 5 weeks during the development phase (makes a good
  344. incentive to add new commands). So, directory 'Empire' contains the binary
  345. for our latest version (last changed last night), along with some rough
  346. and ready documentation and a couple versions of the world-builder program.
  347. It's quite playable as it is, but there are bound to be bugs. Let us know
  348. about them, as well as any you find in the Draco stuff. Have fun!
  349.